Integration Guide

This guide explains how to integrate your store with the Giftme MiniStore SDK, allowing your customers to make purchases using Giftme payment methods.

Overview

The Giftme MiniStore SDK integration consists of three main steps:

1. Authentication - Authenticate your MiniStore to access Giftme's platform
2. Order Tokenization - Create a token representing your order details
3. Payment Processing - Process payments with Giftme

Integration Steps

1. Authentication

To authenticate your MiniStore and get user information:

In your frontend:

• Call giftmeGetAuthCode with your MiniStore ID
• The SDK will handle the authentication process
• When successful, you'll receive the authentication token

Your server-side code to verify user information:

<?php
// Get the auth token from the callback
$authToken = $_GET['token'] ?? '';

// Make a request to Giftme API to get user info
$ch = curl_init('https://api.giftme.com/api/ministore/user');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $authToken
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode !== 200) {
    // Handle error
    echo "Failed to get user information";
    exit;
}

$userData = json_decode($response, true);
// User data contains: id, name, email, phone

2. Order Tokenization

When a customer is ready to check out, tokenize the order on your server:

<?php
// Server-side code to tokenize order
function tokenizeOrder($orderData) {
    $ministoreId = 'YOUR_MINISTORE_ID';
    $ministoreSecret = 'YOUR_MINISTORE_SECRET';

    $ch = curl_init('https://api.giftme.com/api/order/tokenize');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($orderData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-MiniStore-ID: ' . $ministoreId,
        'X-MiniStore-Secret: ' . $ministoreSecret
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        // Handle error
        return ['error' => 'Failed to tokenize order'];
    }

    return json_decode($response, true);
}

// Example usage
$orderData = [
    'amount' => 50.00,
    'currency' => 'JMD',
    'external_reference' => 'ORDER-' . uniqid(),
    'notes' => 'Purchase of Product XYZ',
    'mode' => 'sandbox' // Use 'live' for production
];

$result = tokenizeOrder($orderData);
$orderToken = $result['order_token'] ?? null;

// Return order token to the front-end
echo json_encode(['order_token' => $orderToken]);

3. Payment Processing

Once you have the order token, your front-end will:

• Call giftmeMakePayment with the order token
• The SDK will open the Giftme payment interface
• The customer will select a payment method and complete payment
• You'll receive the payment result in the response

4. Handling Payment Callbacks

Set up a callback endpoint to process the result when payment completes:

<?php
// Payment callback handler
$callbackData = $_GET; // Or $_POST depending on how Giftme sends callbacks

if (isset($callbackData['success']) && $callbackData['success'] === true) {
    // Payment was successful
    $transactionId = $callbackData['transaction_id'] ?? '';
    $externalReference = $callbackData['external_reference'] ?? '';

    // Update your order status
    updateOrderStatus($externalReference, 'paid');

    // Redirect or show confirmation
    header('Location: /order/confirmation?ref=' . $externalReference);
    exit;
} else {
    // Payment failed or was canceled
    $errorMessage = $callbackData['error'] ?? 'Payment failed';

    // Redirect or show error
    header('Location: /order/failed?error=' . urlencode($errorMessage));
    exit;
}

function updateOrderStatus($externalReference, $status) {
    // Your code to update the order status in your database
    // Example:
    // $db->query("UPDATE orders SET status = ? WHERE reference = ?", [$status, $externalReference]);
}

5. Webhook Processing

Set up a webhook endpoint to receive server-to-server payment notifications:

<?php
// Webhook handler
$webhookData = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$ministoreSecret = 'YOUR_MINISTORE_SECRET';

$calculatedSignature = hash_hmac('sha256', json_encode($webhookData), $ministoreSecret);

if ($signature !== $calculatedSignature) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

// Process the webhook data
$transactionId = $webhookData['transaction_id'] ?? '';
$externalReference = $webhookData['external_reference'] ?? '';
$status = $webhookData['status'] ?? '';

// Log the webhook
error_log('Giftme webhook received: ' . json_encode($webhookData));

// Update order status in your system
if ($status === 'completed') {
    // Payment was successful
    updateOrderStatus($externalReference, 'paid');

    // Additional business logic
    // e.g., send confirmation email, update inventory, etc.
}

// Acknowledge receipt of webhook
http_response_code(200);
echo 'Webhook received';

SDK Functions Reference

The Giftme MiniStore SDK provides these main functions:

Function	Description
giftmeGetAuthCode	Opens the Giftme authentication flow and returns a token
giftmeMakePayment	Opens the Giftme payment interface for the provided order token

Testing

1. Start with mode: 'sandbox' to test your integration
2. Verify both callback and webhook processing works correctly
3. Test different payment flows and error conditions

Going Live

When you're ready to go live:

1. Switch to mode: 'live' in your tokenization calls
2. Update your API credentials to production values
3. Ensure your callback URL and webhook URL are properly configured